Skip to main content

Remote credentials

A remote credential lets ApertureDB read media from an external S3 bucket, Google Cloud Storage bucket, or HTTPS origin. It is separate from a database user’s password and from the server credentials used to store its own database.

Register one credential per origin​

Use CreateCredential with origin and key. An origin is s3://bucket, gs://bucket, or https://media.example.com. The scheme selects the provider.

Origins must not contain paths, trailing slashes, query strings, or fragments. HTTPS hostnames are lowercased and port 443 is omitted during registration. Nondefault HTTPS ports identify distinct origins. Object-storage bucket spelling is preserved. Register each bucket separately, even when several use the same key.

[{"CreateCredential": {
"origin": "https://media.example.com",
"key": {"bearer_token": "<origin-token>"}
}}]

An anonymous HTTPS origin still needs a credential, with key: {}. key describes provider fields and HTTPS restrictions. Registration checks the required fields without contacting the provider. Verify access by retrieving a small object afterward. GetCredentials lists registered origins without returning keys.

Use credentials in a later query​

Register the credential and wait for success before submitting a query that reads media from that origin. An AddBlob, AddImage, or AddVideo command accepts a full url instead of an input blob. The object stays at that location. ApertureDB uses the registered credential for the origin; URLs into its own storage bucket are refused.

Creating or changing a credential in the same query as a media command does not change the key used for that query’s media reads, even if the credential command comes first. Submit the credential change separately when the media command needs the new key.

Retrieving media requires a registered credential. Returning a stored URL as a property without fetching its content does not.

Rotate and remove credentials​

UpdateCredential replaces the complete key for an existing origin. Wait for the update to succeed before submitting queries that should use the new key. A request already underway may finish using the previous key. The remote provider can independently revoke a key and cause those reads to fail.

RemoveCredential prevents later requests from reading media at that origin until a credential is registered again. Removal leaves the remote objects and their database records intact. Requests already underway may still finish. Creating, updating, or removing a credential succeeds or rolls back with the query’s other database changes.

In a cluster, other replicas may take a short time to reflect credential changes.

See Configuration File for remote connection and download limits.